home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / X11 / wais / doc / source.txt < prev    next >
Text File  |  1995-05-09  |  8KB  |  243 lines
  1.  
  2.  
  3.                 Source Description Structures
  4.  
  5.                Brewster Kahle brewster@Think.com
  6.                  Harry Morris morris@think.com
  7.                   2/20/91
  8.  
  9.  
  10. A "source description structure" is used by a client of the WAIS system to
  11. contact a database on a server.  This document describes a text encoding of
  12. the source description structure.  This specification is compatible with
  13. the clients that are given out with the WAIS release (version 8 and higher)
  14. and with the Directory of Servers maintained by Thinking Machines.  Example
  15. C code to read and write these structures is available free of charge from
  16. the authors.
  17.  
  18. Note that WAIS end users should never see this structure, since a typical
  19. user will use the source structures retrieved from the directory of servers
  20. or those created by waisindex, and interact with them through a client user
  21. interface.
  22.  
  23. Philosophy:
  24. -----------
  25.  
  26. Sources form the conceptual link between an information user and a database
  27. vendor.  As such, they serve two functions.  First, they provide a means
  28. for the database vendor to inform the user of database specific
  29. information, in particular, how to contact the database, and how much it
  30. costs to do so.  Second, they serve as repositories for the user's
  31. customizations.
  32.  
  33. The fields which describe how to contact a server, what database name to
  34. use, and how much the service costs are required.  The other fields are
  35. strictly optional.  Servers may choose to use them to make suggestions
  36. about how their service might be used, or clients may choose to let the
  37. user modify certain options.  While not all clients may want or need all
  38. the optional fields, it is in everyone's best interest to have any
  39. particular function expressed in a single format that all can share.  The
  40. optional fields presented here are ones we have found useful.  If you have
  41. suggestions for fields that should be added to the specification, please
  42. contact the authors.
  43.  
  44. Clients should always be prepared to ignore the non-required fields.
  45.  
  46. An example source structure is:
  47.  
  48. (:source 
  49.   :version          3 
  50.   :ip-name         "quake.think.com"
  51.   :ip-address         "192.31.181.1"
  52.   :tcp-port         210
  53.   :maintainer         "brewster@think.com"
  54.   :database-name     "directory-of-servers"
  55.   :cost          0.00
  56.   :cost-unit         :free
  57.   :description         
  58. "The directory of servers is a white pages of servers maintained by many
  59. others.  This one is maintained by Thinking Machines Corporation on the
  60. internet.  To submit new entries to the directory of servers, mail to
  61. wais-directory-of-servers@quake.think.com. -brewster"
  62.   :update-time         (:time-interval :interval :daily 
  63.                   :day 0 :hour 1 :min 30)
  64.   )
  65.  
  66. Syntax:
  67. -------
  68.  
  69. The syntax is based on a subset the Common Lisp printer format (see Common
  70. Lisp, the Manual, by Guy Steele).  We chose this format because is easy to
  71. parse on many different platforms, and from many different languages.  The
  72. format is summarized below.
  73.  
  74. A source is a structure but written as a list.  Every structure is written
  75. in the form
  76.  
  77.     (<structure-type>
  78.      <keyword> <value>
  79.      <keyword> <value>
  80.      ...
  81.     )
  82.  
  83. Structure types and keywords are always symbols.  Value may be a symbol,
  84. decimal, integer, string, array, ANY, or another structure.  The Common
  85. Lisp structure format was not used because many lisp implementations do not
  86. handle unknown keywords well.
  87.  
  88. Symbols are preceded with a colon (in the keyword package), and consist of
  89. all lower case letters with embedded hyphens. Strictly speaking, symbols
  90. are not case sensitive, but some clients seem to be ignoring this.
  91. Sticking with lower case is safe.  Example symbols :2foo and :bar-baz3.
  92.  
  93. Strings start and end with '"'; if a '"' is to appear in the string, then
  94. it a '\' is inserted before it.  If a '\' is to appear then, '\\' is used.
  95.  
  96. Integers are written without a decimal point.  Floating point numbers are
  97. written with a decimal point.
  98.  
  99. Arrays are written as #(value value value ...).  For example, a 1
  100. dimensional array of numbers looks like #(115 101 120).
  101.  
  102. Lists are formed by simply enclosing enumerated items in parentheses.  The
  103. items are separated by white space.  For example, a list of numbers looks
  104. like (3 4 57).
  105.  
  106. Z39.50 byte arrays (ANYs) are written as structs with length and byte keys
  107. or as a string.  For example, (:any :length 3 :bytes #(115 101 120)) or
  108. "foo".  The string form may only used when every character is a printable
  109. character; this is used to reduce the structure size and increase
  110. readability, but is optional.
  111.  
  112.  
  113.  
  114. Required Fields (set by vendor):
  115. -------------------------------
  116.  
  117. :version <integer>  
  118. The number is the major version number of the source structure format.  The
  119. current version is 3.  This must be the first slot.
  120.  
  121. :database-name <string> 
  122. These are the names of the databases on the server.  It is a list of
  123. databases, separated by <XXX> characters
  124.  
  125. at least one of :ip-name, :ip-address.  Both combination may be specified.
  126. XXX what about modems
  127.  
  128.     :ip-address  <string> a legal internet address such as
  129.      "192.31.181.1"  
  130.  
  131.     :ip-name <string> a legal internet name such as "quake.think.com" 
  132.  
  133. :cost <float>
  134. Cost of using this server. see :cost-unit for units
  135.  
  136. :cost-unit <cost-unit-type>
  137. one of the following values.
  138.  
  139.     :free, 
  140.     :dollars-per-session, 
  141.     :dollars-per-minute, 
  142.     :dollars-per-query, 
  143.     :dollars-per-retrieval,
  144.     :other
  145.  
  146.  
  147. Optional Fields set by vendor:
  148. ------------------------------
  149.  
  150. :tcp-port <integer>
  151. The tcp port to connect to.  The default is 210, the official Z39.50 port
  152. number.
  153.  
  154. :configuration <string>
  155. (XXX weird stuff, plus what contact method to use! XXX)
  156.  
  157. :script <string>
  158. A string of commands to be interpreted after establishing the connection to
  159. the server.  This may involve loging in, authentication, configuring the
  160. connection etc.  The commands are those used by White Knight (yuk).  They
  161. are currently only used in making modem connections (XXX it is possible
  162. that tcp might want to use this too, and that we may want to run scripts
  163. just before starting the connection, just after starting the connection,
  164. and just before closing the connection).
  165.  
  166. :maintainer <string>
  167. An english description of who to contact for information.
  168.  
  169. :description <string>
  170. An english description of the database.
  171.  
  172. :update-time <time-interval>
  173. The interval at which the server's data is updated.  This is a structure of
  174. the form
  175.  
  176.     (:time-interval 
  177.           :interval      <interval-type>
  178.           :day          <integer>
  179.           :hour          <integer>
  180.           :min          <integer> 
  181.           ) 
  182.  
  183.     where interval-type is one of 
  184.     
  185.     :continuous - day, hour, min are ignored
  186.     :hourly - min is used
  187.     :daily - hour and min are used
  188.     :weekly - day is day of week, hour and min are used
  189.     :monthly - day is day of month, hour and min are used
  190.     :unschedualed - day, hour, min are ignored
  191.     (XXX what about yearly)
  192.  
  193. Optional Fields set by user:
  194. ----------------------------
  195.  
  196. :font <string>
  197. Font for displaying this source's documents.  This is machine specific,
  198. clients should use their default if they don't understand the value.  Note
  199. that a vendor may wish to suggest a font for use with its database.
  200.  
  201. :font-size <integer>    
  202. The size to use for displaying the font.  The units are machine dependent.
  203.  
  204. :window-geometry  <rect>
  205. The positioning of the source editing window (if there is one) in machine
  206. dependent units.  It is of the form
  207.     
  208.     (:rect  
  209.         :left    <integer>
  210.         :top      <integer>  
  211.         :right  <integer>  
  212.         :bottom <integer>
  213.         ) 
  214.  
  215. :confidence  <integer>
  216. A subjective evaluation of how "good" the server is.  This may be used by
  217. clients to help score documents or allocate funds.
  218.  
  219. :num-docs-to-request  <integer>
  220. How many documents to ask for from this source.
  221.  
  222. :contact-at <time-interval (see :update-time)>
  223. Clients which can automatically contact a server on behalf of their user
  224. use this field to determine when.  Note, multitasking clients may have
  225. system level utilities for this purpose.
  226.  
  227. :last-contacted <absolute-time>
  228. A record of the last time the source was contacted.  The format is
  229.  
  230.      (:absolute-time 
  231.               :year      <integer>
  232.               :month  <integer>
  233.               :mday      <integer>
  234.               :hour      <integer>
  235.               :minute <integer>
  236.               :second <integer> (second = 61 means the server has not been
  237.                     contacted)
  238.               ) 
  239.  
  240. :timeout <integer>
  241. The number of seconds to give the this source's server to respond to a
  242. query before disconnecting the communications circuit.
  243.